Get notifications about Kanzi Studio events and get access to the core Kanzi Studio operations, such as access to the Kanzi Studio project, get input from the user, and show notifications. More...

Inheritance diagram for KanziStudio:

[legend]

Collaboration diagram for KanziStudio:

[legend]

Public Member Functions
void	BeginEmphasize (EmphasizeFlag target)
	Starts emphasizing an ongoing operation.

bool	CanExecutePluginCommand (PluginCommand command, IEnumerable< ProjectItem > items)

bool	CanExecutePluginCommand (string commandName, IEnumerable< ProjectItem > items)

void	ExecutePluginCommand (PluginCommand command, IEnumerable< ProjectItem > items)

void	ExecutePluginCommand (string commandName, IEnumerable< ProjectItem > items)

void	FinishEmphasize (EmphasizeFlag type)
	Ends emphasizing an ongoing operation and allows Kanzi Studio to return to the normal state.

DateTime?	GetExpirationDateForLicensedFeature (string featureId)
	Gets the expiration date of the license of an optional feature.

string	GetFolderPathFromUser (string dialogTitle, string initialDirectory, string userPreferencesSetting)
	Prompts the user to provide a path to a directory.

string	GetFolderPathFromUser (string dialogTitle, string initialPath)

string	GetPathFromUser (string dialogTitle, string initialDirectory, string userPreferencesSetting, string defaultExtension, string filter, PathDialogType pathDialogType, bool multiselect)
	Opens a Windows dialog that allows the user to browse their computer to select a path.

string	GetUserInput (string title, string prompt)
	Creates a dialog box which prompts the user to provide input.

string	GetUserInput (string title, string prompt, IEnumerable< string > options, string initialValue)
	Displays a dialog box which prompts the user to select a value from one of the predefined options using a drop-down menu.

MessageBoxResult	GetUserInput (string title, string prompt, MessageBoxButton messageBoxButton)

string	GetUserInput (string title, string prompt, MessageBoxButton messageBoxButton, string extraOptionText)

string	GetUserInput (string title, string prompt, string initialValue)
	Creates a dialog box which prompts the user to provide input.

void	Log (string message)
	Writes to the Kanzi Studio Log window.

void	Log (string message, Exception exception)
	Writes information about an exception to the Kanzi Studio Log window.

void	Log (string message, LogLevel logLevel)
	Writes to the Kanzi Studio Log window.

void	Redo ()

bool	RegisterPropertyRouter (PropertyRouter router)
	Registers a property router.

void	SendPreviewCommand (string name, object[] args)
	Sends commands to the Kanzi Studio Preview.

void	ShowMessageBox (string text, bool isModal)
	Creates a window with a message.

void	ShowMessageBox (string text, string caption, bool isModal)
	Displays a window with a title and a message.

void	SubscribeToPropertyValueChanges (string projectItemPath, string propertyName)
	Tracks property changes in the Kanzi Studio Preview for the project item you set in this function.

void	Undo ()

bool	UnregisterPropertyRouter (PropertyRouter router)
	Unregisters a property router.

void	UnsubscribeFromPropertyValueChanges (string projectItemPath, string propertyName)
	Stops tracking the property changes in the Kanzi Studio Preview for the project item you set in this function.

Properties
Project	ActiveProject `[get]`

IEnumerable< ProjectItem >	ClipboardItems `[get]`

Commands	Commands `[get]`

string	FactoryContentPath `[get]`

string	KanziEnvironmentVariablesBatPath `[get]`

DirectoryInfo	KanziExecutableDirectory `[get]`

string	KanziHome `[get]`

DirectoryInfo	KanziWorkspaceDirectory `[get]`

IPackageUriAccessor	PackageUriAccessor `[get]`

string	Prefab3DCompositionRootName `[get]`
	If the Prefab composition root is a 3D node, Preview patching makes the root node point to "<Isolation Preview Viewport>/<Isolation Preview Scene Placeholder>/<Isolation preview model placeholder>".

Project	PrimaryProject `[get]`

Project	Project `[get]`
	Since introduction of multi-project feature, the project to use is not anymore self-evident, making KanziStudio.Project obsolete.

IEnumerable< ProjectItem >	SelectedItems `[get]`

Solution	Solution `[get]`

string	StatusBarText `[get, set]`

IUserPreferences	UserPreferences `[get]`
	Provides access to Kanzi Studio user preferences.

IGenericUtilities	Utilities `[get]`

Version	Version `[get]`
	Gets the version of Kanzi Studio where you run the plugin.

Events
EventHandler< ProjectEventArgs >	BinaryExported
	Occurs after Kanzi Studio exports the kzb file of the project.

EventHandler	PreviewExited
	Occurs when the Kanzi Studio Preview closes.

EventHandler< PreviewPropertyChangedEventArgs >	PreviewPropertyChanged

EventHandler	PreviewStarted
	Occurs when the Kanzi Studio Preview starts.

EventHandler< PreviewStartingEventArgs >	PreviewStarting
	Occurs when the Kanzi Studio Preview is starting.

EventHandler< ProjectPathEventArgs >	ProjectClosed
	Occurs when the project is closed.

EventHandler< ProjectEventArgs >	ProjectOpened
	Occurs when the project is opened.

EventHandler< ProjectSavingEventArgs >	ProjectSaved
	Occurs when the project is saved.

EventHandler	SelectionChanged
	Occurs when the selection of a node or a resource in Kanzi Studio changes.

EventHandler< ProjectPathEventArgs >	SolutionClosed
	Occurs when the primary project is closed.

EventHandler< ProjectEventArgs >	SolutionOpened
	Occurs when a new primary project is created or loaded.

EventHandler< StatusEventArgs >	StatusChanged

Detailed Description

Get notifications about Kanzi Studio events and get access to the core Kanzi Studio operations, such as access to the Kanzi Studio project, get input from the user, and show notifications.

Member Function Documentation

◆ BeginEmphasize()

void BeginEmphasize ( EmphasizeFlag target )

Starts emphasizing an ongoing operation.

Parameters

target Target location, for example a preview window.

See also: FinishEmphasize

◆ FinishEmphasize()

void FinishEmphasize ( EmphasizeFlag type )

Ends emphasizing an ongoing operation and allows Kanzi Studio to return to the normal state.

Parameters

type	Target location, for example a preview window.

See also: BeginEmphasize

◆ GetExpirationDateForLicensedFeature()

DateTime? GetExpirationDateForLicensedFeature ( string featureId )

Gets the expiration date of the license of an optional feature.

Parameters

featureId The feature ID of the optional feature.

Returns

One of these values:

Expiration date, if a license exists for the feature ID
DateTime.MaxValue, if the license is permanent
Null, if no license exists for the feature ID.

◆ GetFolderPathFromUser()

string GetFolderPathFromUser	(	string	dialogTitle,
		string	initialDirectory,
		string	userPreferencesSetting )

Prompts the user to provide a path to a directory.

Parameters

dialogTitle	The title of the dialog box.
initialDirectory	Initial directory where the folder dialog is opened.
userPreferencesSetting	A key to be used for storing the last selected folder in the user preferences. Set as null not to save the path. If an existing value is found from user preferences, that is used over the value supplied in initialDirectory parameter.

Returns: The select folder path or null if cancelled.

◆ GetPathFromUser()

string GetPathFromUser	(	string	dialogTitle,
		string	initialDirectory,
		string	userPreferencesSetting,
		string	defaultExtension,
		string	filter,
		PathDialogType	pathDialogType,
		bool	multiselect )

Opens a Windows dialog that allows the user to browse their computer to select a path.

You can use this function to get a path to either open or save a file.

Parameters

dialogTitle	The title of the dialog box.
initialDirectory	The initial directory where to open the dialog.
userPreferencesSetting	The user preferences key to use to store the last selected directory. Set as null not to save the path. If an existing value is found from user preferences, that is used over the value supplied in initialDirectory parameter.
defaultExtension	The default file extension to use to open or save the file.
filter	The filter definition that sets which file extensions the dialog allows the user to select.
pathDialogType	The type of the dialog. Use PathDialogType.OPEN for the open file dialog and PathDialogType.SAVE for the save file dialog.
multiselect	When opening files, sets whether the user is allowed to select multiple files.

Returns: The absolute path to the selected file. If user cancels the operation, the function returns null.

See also: GetUserInput(string, string)

Examples

To open a Windows dialog which allows the user to browse their computer and select a path:

        public void Execute(PluginCommandParameter parameter)
        {
            // Open the standard Windows dialog box where you can select which file on your computer you want to open.
            // In the dialog box set:
            // - Title to "Select the file you want to open".
            // - Open the dialog in the current directory.
            // - Store the path to the selected directory in the GetPathFromUser key in the Kanzi Studio user preferences.
            // - Use .xml as the default extension for opening the file.
            // - Allow the user to select only files with .xml and .txt extensions.
            // - Create an open dialog.
            // - Allow selection of multiple files in the dialog.
            studio.GetPathFromUser(
                "Select the file you want to open", 
                ".", 
                "GetPathFromUser", 
                ".xml", 
                "XML files (*.xml)|*.xml|Plain text files (*.txt)|*.txt", 
                PathDialogType.OPEN, 
                true);
        }

◆ GetUserInput() [1/3]

string GetUserInput	(	string	title,
		string	prompt )

Creates a dialog box which prompts the user to provide input.

For example, you can use this function to get the path of a node where you want your plugin to start executing its commands.

Parameters

title	The title of the dialog box.
prompt	The message you want to show in the dialog box.

Returns: The user input. If user cancels the operation, the function returns null.

Examples

To create a dialog box with a title and prompt:

        public void Execute(PluginCommandParameter parameter)
        {
            // Display a dialog box with:
            // - Title "Where do you want to create the node?"
            // - Prompt message "Enter the path where you want to create the node"
            studio.GetUserInput(
                "Where do you want to create the node?", 
                "Enter the path where you want to create the node");
        }

◆ GetUserInput() [2/3]

string GetUserInput	(	string	title,
		string	prompt,
		IEnumerable< string >	options,
		string	initialValue )

Displays a dialog box which prompts the user to select a value from one of the predefined options using a drop-down menu.

Parameters

title	The title of the dialog box.
prompt	The message you want to show in the dialog box.
options	The options shown in a drop-down box from which the user can select.
initialValue	The value preselected in the drop-down menu.

Returns: The user input. If user cancels the operation, the function returns null.

◆ GetUserInput() [3/3]

string GetUserInput	(	string	title,
		string	prompt,
		string	initialValue )

Creates a dialog box which prompts the user to provide input.

For example, you can use this function to get the path of a node where you want your plugin to start executing its commands.

Parameters

title	The title of the dialog box.
prompt	The message you want to show in the dialog box.
initialValue	The predefined value entered in the prompt.

Returns: The user input. If user cancels the operation, the function returns null.

See also: GetPathFromUser

Examples

To create a dialog box with a title, a prompt, and a text box with a predefined value:

        public void Execute(PluginCommandParameter parameter)
        {
            // Display a dialog box with:
            // - Title "Where do you want to create the node?"
            // - Prompt message "Enter the path where you want to create the node"
            // - Text box with a predefined value set to "Screen/Screens/RootPage"
            studio.GetUserInput(
                "Where do you want to create the node?", 
                "Enter the path where you want to create the node", 
                "Screen/Screens/RootPage");
        }

◆ Log() [1/3]

void Log ( string message )

Writes to the Kanzi Studio Log window.

For example, you can use this function to inform the user about the plugin progress in the Log window.

Parameters

message The message you want to print to the Log window.

Examples

To print a message to the Kanzi Studio Log window:

        public void Execute(PluginCommandParameter parameter)
        {
            // Print "Success!" to the Kanzi Studio Log window.
            studio.Log("Success!");
        }

◆ Log() [2/3]

void Log	(	string	message,
		Exception	exception )

Writes information about an exception to the Kanzi Studio Log window.

Parameters

message	The message you want to print to the Log window before the exception information.
exception	The exception to be logged.

◆ Log() [3/3]

void Log	(	string	message,
		LogLevel	logLevel )

Writes to the Kanzi Studio Log window.

For example, you can use this function to inform the user about the plugin progress in the Log window.

Parameters

message	The message you want to print to the Log window.
logLevel	The level of the message you want to print to the Log window.

Examples

To print a message to the Log window as a regular notification:

        public void Execute(PluginCommandParameter parameter)
        {
            // Print "Hello world!" to the Kanzi Studio Log window.
            studio.Log("Hello world!", LogLevel.INFO);
        }

To print a message to the Log window as a warning:

        public void Execute(PluginCommandParameter parameter)
        {
            // Print "Warning!" with a yellow background to the Kanzi Studio Log window.
            studio.Log("Warning!", LogLevel.WARNING);
        }

◆ RegisterPropertyRouter()

bool RegisterPropertyRouter ( PropertyRouter router )

Registers a property router.

A property router can interfere when a user edits properties in Kanzi Studio.

Parameters

router The router to register.

Returns: True, if router was registered. False, if the router is already registered.

See also: UnregisterPropertyRouter

◆ SendPreviewCommand()

void SendPreviewCommand	(	string	name,
		object[]	args )

Sends commands to the Kanzi Studio Preview.

Parameters

name	The name of the command you want to send to the Preview.
args	The command arguments you want to send (must be serializable.)

◆ ShowMessageBox() [1/2]

void ShowMessageBox	(	string	text,
		bool	isModal )

Creates a window with a message.

For example, you can use this function to show a message to the user.

Parameters

text	The message you want to show in the window.
isModal	Whether the window is modal. When set to `true` you cannot use the main Kanzi Studio window until you confirm the message in this window.

Examples

To create a modal window which displays a message:

        public void Execute(PluginCommandParameter parameter)
        {
            // Display a modal window with the message "All nodes created".
            // The second parameter sets whether the window is modal.
            studio.ShowMessageBox("All nodes created.", true);
        }

◆ ShowMessageBox() [2/2]

void ShowMessageBox	(	string	text,
		string	caption,
		bool	isModal )

Displays a window with a title and a message.

For example, you can use this function to show a message to the user.

Parameters

text	The message you want to show in the window.
caption	The title of the window.
isModal	Whether the window is modal. When set to `true` you cannot use the main Kanzi Studio window until you confirm the message in this window.

Examples

To create a modal window with a title and which displays a message:

        public void Execute(PluginCommandParameter parameter)
        {
            // Display a modal window with the title "Success!" and the message "All nodes created".
            // The third parameter sets whether the window is modal.
            studio.ShowMessageBox("All nodes created.", "Success!", true);
        }

◆ SubscribeToPropertyValueChanges()

void SubscribeToPropertyValueChanges	(	string	projectItemPath,
		string	propertyName )

Tracks property changes in the Kanzi Studio Preview for the project item you set in this function.

Triggers change events in project item and in this class.

Parameters

projectItemPath	The path to the project item for which you want to track property changes.
propertyName	The name of the property the changes of which you want to track.

See also: UnsubscribeFromPropertyValueChanges

◆ UnregisterPropertyRouter()

bool UnregisterPropertyRouter ( PropertyRouter router )

Unregisters a property router.

A property router can interfere when a user edits properties in Kanzi Studio.

Parameters

router The router to unregister.

Returns: True, if the router was successfully unregistered. False, if no such router was registered.

See also: RegisterPropertyRouter

◆ UnsubscribeFromPropertyValueChanges()

void UnsubscribeFromPropertyValueChanges	(	string	projectItemPath,
		string	propertyName )

Stops tracking the property changes in the Kanzi Studio Preview for the project item you set in this function.

Parameters

projectItemPath	The path to the project item for which you want to stop tracking property changes.
propertyName	The name of the property the changes of which you want to stop tracking.

See also: SubscribeToPropertyValueChanges

Property Documentation

◆ Prefab3DCompositionRootName

string Prefab3DCompositionRootName

get

If the Prefab composition root is a 3D node, Preview patching makes the root node point to "<Isolation Preview Viewport>/<Isolation Preview Scene Placeholder>/<Isolation preview model placeholder>".

This member returns the new name of the composition root node.

The new name of the composition root node when composing Prefab of a 3D node.

◆ Project

Project Project

get

Since introduction of multi-project feature, the project to use is not anymore self-evident, making KanziStudio.Project obsolete.

Use PrimaryProject to get the root of the project hierarchy. Use ActiveProject to get the project that is currently active in UI. This member will return the ActiveProject.

◆ UserPreferences

IUserPreferences UserPreferences

get

Provides access to Kanzi Studio user preferences.

Use this to store settings that are not project dependent.

◆ Version

Version Version

get

Gets the version of Kanzi Studio where you run the plugin.

The version of Kanzi Studio.

Examples

To get the major, minor, revision, and build numbers of the Kanzi Studio where you run the plugin:

        public void Execute(PluginCommandParameter parameter)
        {
            // Print the Kanzi Studio version in the format Major.Minor.Revision.Build
            // to the Kanzi Studio Log window.
            studio.Log(
                studio.Version.Major + "." + 
                studio.Version.Minor + "." + 
                studio.Version.Revision + "." + 
                studio.Version.Build);
        }

Event Documentation

◆ BinaryExported

EventHandler<ProjectEventArgs> BinaryExported

Occurs after Kanzi Studio exports the kzb file of the project.

Examples

To subscribe to the BinaryExported event:

        // Create the event handler and subscribe to the BinaryExported event to get 
        // notified when Kanzi Studio finishes exporting the kzb file of the project.
        public void Execute(PluginCommandParameter parameter)
        {
            // Create the event handler that is set off when Kanzi Studio finishes
            // exporting the kzb file of the project.
            studio.BinaryExported += Studio_BinaryExported;
        }
 
        private void Studio_BinaryExported(object sender, ProjectEventArgs e)
        {
            // When Kanzi Studio finishes exporting the kzb file of the project,
            // print a message to the Kanzi Studio Log window.
            studio.Log("Finished exporting the kzb file of the project \"" + e.Project.Name + "\".");
        }
 

◆ PreviewExited

EventHandler PreviewExited

Occurs when the Kanzi Studio Preview closes.

See also: PreviewStarted

Examples

To subscribe to the PreviewExited event:

        // Create the event handler and subscribe to the PreviewExited event to get notified
        // when the Kanzi Studio Preview closes.
        public void Execute(PluginCommandParameter parameter)
        {
            // Create the event handler that is set off when the Preview closes.
            studio.PreviewExited += Studio_PreviewExited;
        }
 
        private void Studio_PreviewExited(object sender, EventArgs e)
        {
            // When the Preview closes, print a message to the Kanzi Studio Log window.
            studio.Log("The Preview closed.");
        }

◆ PreviewStarted

EventHandler PreviewStarted

Occurs when the Kanzi Studio Preview starts.

See also: PreviewExited

Examples

To subscribe to the PreviewStarted event:

        // Create the event handler and subscribe to the PreviewStarted event to get notified
        // when the Kanzi Studio Preview starts.
        public void Execute(PluginCommandParameter parameter)
        {
            // Create the event handler that is set off when the Preview starts.
            studio.PreviewStarted += Studio_PreviewStarted;
            studio.Log("PreviewStarted subscribed.");
        }
 
        private void Studio_PreviewStarted(object sender, EventArgs e)
        {
            // When the Preview starts, print a message to the Kanzi Studio Log window.
            studio.Log("The Preview started.");
        }

◆ PreviewStarting

EventHandler<PreviewStartingEventArgs> PreviewStarting

Occurs when the Kanzi Studio Preview is starting.

You can cancel this event.

See also: PreviewStarted

Examples

To subscribe to the PreviewStarting event:

        // Create the event handler and subscribe to the PreviewStarting event to get notified 
        // when the Kanzi Studio Preview is starting.
        public void Execute(PluginCommandParameter parameter)
        {
            // Create the event handler that is set off when the Preview is starting.
            studio.PreviewStarting += Studio_PreviewStarting;
            studio.Log("PreviewStarting subscribed.");
        }
 
        private void Studio_PreviewStarting(object sender, PreviewStartingEventArgs e)
        {
            // When the Preview is starting, cancel it.
            e.Cancel("Preview startup canceled by an example for demonstration purposes.");
        }

◆ ProjectClosed

EventHandler<ProjectPathEventArgs> ProjectClosed

Occurs when the project is closed.

See also: ProjectOpened, ProjectSaved

Examples

To subscribe to the ProjectClosed event:

        // Create the event handler and subscribe to the ProjectClosed event to get notified when a project is closed.
        public void Execute(PluginCommandParameter parameter)
        {
            // Create the event handler that is set off when a project is closed.
            studio.ProjectClosed += Studio_ProjectClosed;
        }
 
        private void Studio_ProjectClosed(object sender, ProjectPathEventArgs e)
        {
            // When the project is closed, show a dialog box with a message about project closing.
            studio.ShowMessageBox("The project \"" + e.ProjectPath + "\" is closed.", false);
        }
 

◆ ProjectOpened

EventHandler<ProjectEventArgs> ProjectOpened

Occurs when the project is opened.

This can happen when the primary project of solution is loaded / created or when a sub-project is loaded or created.

See also: ProjectClosed, ProjectSaved

Examples

To subscribe to the ProjectOpened event:

        // Create the event handler and subscribe to the ProjectOpened event to get notified when a project is opened.
        public void Execute(PluginCommandParameter parameter)
        {
            // Create the event handler that is set off when a project is opened.
            studio.ProjectOpened += Studio_ProjectOpened;
        }
 
        private void Studio_ProjectOpened(object sender, EventArgs e)
        {
            // When the project is opened, show a dialog box with the message "The project is opened."
            studio.Log("The project is opened.");
        }
 

◆ ProjectSaved

EventHandler<ProjectSavingEventArgs> ProjectSaved

Occurs when the project is saved.

See also: ProjectOpened, ProjectClosed

Examples

To subscribe to the ProjectSaved event:

        // Create the event handler and subscribe to the ProjectSaved event to get notified when a project is saved.
        public void Execute(PluginCommandParameter parameter)
        {
            // Create the event handler that is set off when a project is saved.
            studio.ProjectSaved += Studio_ProjectSaved;
        }
 
        private void Studio_ProjectSaved(object sender, ProjectEventArgs e)
        {
            // When the project is saved, print a message to the Kanzi Studio Log window.
            studio.Log("The project \"" + e.Project.Name + "\" is saved.");
        }
 

◆ SelectionChanged

EventHandler SelectionChanged

Occurs when the selection of a node or a resource in Kanzi Studio changes.

For example, Kanzi Studio sets off this event when you select a node in a Project or Nodes windows, when you select a library, a directory, or a resource in the Library, or any of the resource windows.

Examples

To subscribe to the SelectionChanged event:

        // Create the event handler and subscribe to the SelectionChanged event to get notified 
        // when the selection of a node or a resource in Kanzi Studio changes.
        public void Execute(PluginCommandParameter parameter)
        {
            // Create the event handler that is set off when the selection of a node or a resource
            // in Kanzi Studio changes.
            studio.SelectionChanged += Studio_SelectionChanged;
        }
 
        private void Studio_SelectionChanged(object sender, EventArgs e)
        {
            // When the selection of a node or a resource in Kanzi Studio changes,
            // print a message to the Kanzi Studio Log window.
            studio.Log("The node or resource selection changed.");
        }
 

◆ SolutionClosed

EventHandler<ProjectPathEventArgs> SolutionClosed

Occurs when the primary project is closed.

Examples

To subscribe to the SolutionClosed event:

        // Create the event handler and subscribe to the SolutionClosed event to get notified when a Kanzi solution is closed.
        public void Execute(PluginCommandParameter parameter)
        {
            // Create the event handler that is set off when a project is closed.
            studio.SolutionClosed += Studio_SolutionClosed;
        }
 
        private void Studio_SolutionClosed(object sender, EventArgs e)
        {
            // When the solution is closed, show a dialog box with the message "The solution is closed."
            studio.ShowMessageBox("The solution is closed.", false);
        }
 

Public Member Functions

Properties

Events

Detailed Description

Member Function Documentation

◆ BeginEmphasize()

◆ FinishEmphasize()

◆ GetExpirationDateForLicensedFeature()

◆ GetFolderPathFromUser()

◆ GetPathFromUser()

◆ GetUserInput() [1/3]

◆ GetUserInput() [2/3]

◆ GetUserInput() [3/3]

◆ Log() [1/3]

◆ Log() [2/3]

◆ Log() [3/3]

◆ RegisterPropertyRouter()

◆ SendPreviewCommand()

◆ ShowMessageBox() [1/2]

◆ ShowMessageBox() [2/2]

◆ SubscribeToPropertyValueChanges()

◆ UnregisterPropertyRouter()

◆ UnsubscribeFromPropertyValueChanges()

Property Documentation

◆ Prefab3DCompositionRootName

◆ Project

◆ UserPreferences

◆ Version

Event Documentation

◆ BinaryExported

◆ PreviewExited

◆ PreviewStarted

◆ PreviewStarting

◆ ProjectClosed

◆ ProjectOpened

◆ ProjectSaved

◆ SelectionChanged

◆ SolutionClosed